{/* Copyright 2025 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout} from '../../src/Layout';
export default Layout;
import {InterfaceType} from '../../src/types';
import {FunctionAPI} from '../../src/FunctionAPI';
import docs from 'docs:@react-aria/landmark';
export const section = 'Interactions';
export const description = 'Enables keyboard navigation between page landmarks.';

# useLandmark

<PageDescription>{docs.exports.useLandmark.description}</PageDescription>

```tsx render
"use client";
import {useLandmark} from 'react-aria';
import {useRef} from 'react';

function Navigation(props) {
  let ref = useRef<HTMLElement | null>(null);
  let {landmarkProps} = useLandmark({...props, role: 'navigation'}, ref);
  return (
    <nav ref={ref} {...props} {...landmarkProps}>
      {props.children}
    </nav>
  );
}

function Region(props) {
  let ref = useRef<HTMLElement | null>(null);
  let {landmarkProps} = useLandmark({...props, role: 'region'}, ref);
  return (
    <article ref={ref} {...props} {...landmarkProps}>
      {props.children}
    </article>
  );
}

function Search(props) {
  let ref = useRef<HTMLFormElement | null>(null);
  let {landmarkProps} = useLandmark({...props, role: 'search'}, ref);
  return (
    <form ref={ref} {...props} {...landmarkProps}>
      <h2 id="search-header">Search</h2>
      <input aria-labelledby="search-header" type="search" />
    </form>
  );
}

<div>
  <Navigation>
    <h2>Navigation</h2>
    <ul>
      <li><a href="#">Link 1</a></li>
      <li><a href="#">Link 2</a></li>
    </ul>
  </Navigation>
  <Search />
  <Region aria-label="Example region">
    <h2>Region</h2>
    <p>Example region with no focusable children.</p>
  </Region>
</div>
```

## Features

Landmarks provide a way to designate important subsections of a page. They allow screen reader users to get an overview of the various sections of the page, and jump to a specific section.
By default, browsers do not provide a consistent way to navigate between landmarks using the keyboard.
The `useLandmark` hook enables keyboard navigation between landmarks, and provides a consistent experience across browsers.

* <Keyboard>F6</Keyboard> and <Keyboard>Shift+F6</Keyboard> key navigation between landmarks
* <Keyboard>Alt+F6</Keyboard> key navigation to the main landmark
* Support for navigating nested landmarks

## Anatomy

Landmark elements can be registered with the `useLandmark` hook. The `role` prop is required.

Pressing <Keyboard>F6</Keyboard> will move focus to the next landmark on the page, and pressing <Keyboard>Shift+F6</Keyboard> will move focus to the previous landmark.
If an element within a landmark was previously focused before leaving that landmark, focus will return to that element when navigating back to that landmark.
<Keyboard>Alt+F6</Keyboard> will always move focus to the main landmark if it has been registered.

If multiple landmarks are registered with the same role, they should have unique labels, which can be provided by aria-label or aria-labelledby.

For an example of landmarks in use, see the [useToastRegion](Toast/useToast.html#anatomy) documentation.

## API

<FunctionAPI function={docs.exports.useLandmark} links={docs.links} />

### AriaLandmarkProps

<InterfaceType {...docs.exports.AriaLandmarkProps} />

### LandmarkAria

<InterfaceType {...docs.exports.LandmarkAria} />
